home *** CD-ROM | disk | FTP | other *** search
/ ADA Programming Guide / ADA Programming Guide.iso / adatutor / lrmrdr / chap14.doc < prev    next >
Text File  |  1996-01-30  |  93KB  |  2,240 lines

  1. >                              14. Input-Output
  2.  
  3.  
  4. Input-output  is  provided in the language by means of predefined packages.
  5. The  generic  packages  SEQUENTIAL_IO  and  DIRECT_IO  define  input-output
  6. operations  applicable  to  files  containing  elements  of  a  given type.
  7. Additional operations for text input-output are  supplied  in  the  package
  8. TEXT_IO.   The  package  IO_EXCEPTIONS defines the exceptions needed by the
  9. above three packages.  Finally, a  package  LOW_LEVEL_IO  is  provided  for
  10. direct control of peripheral devices.
  11.  
  12.  
  13. References:   direct_io  package  14.2  14.2.4, io_exceptions package 14.5,
  14. low_level_io package  14.6,  sequential_io  package  14.2  14.2.2,  text_io
  15. package 14.3
  16.  
  17. > 14.1  External Files and File Objects
  18.  
  19.  
  20. Values input from the external environment of the program, or output to the
  21. environment, are considered to occupy external files.  An external file can
  22. be  anything external to the program that can produce a value to be read or
  23. receive a value to be written.  An external file is identified by a  string
  24. (the  name).   A  second  string  (the form) gives further system-dependent
  25. characteristics that may be associated with the file, such as the  physical
  26. organization   or   access   rights.    The   conventions   governing   the
  27. interpretation of such strings must be documented in Appendix F.
  28.  
  29.  
  30. Input and output operations are expressed as operations on objects of  some
  31. file  type,  rather  than  directly in terms of the external files.  In the
  32. remainder of this chapter, the term file is always used to refer to a  file
  33. object;   the term external file is used otherwise.  The values transferred
  34. for a given file must all be of one type.
  35.  
  36.  
  37. Input-output for sequential files of values of a  single  element  type  is
  38. defined  by  means  of  the generic package SEQUENTIAL_IO.  The skeleton of
  39. this package is given below.
  40.  
  41.  
  42.     with IO_EXCEPTIONS;
  43.     generic
  44.        type ELEMENT_TYPE is private;
  45.     package SEQUENTIAL_IO is
  46.        type FILE_TYPE is limited private;
  47.  
  48.        type FILE_MODE is (IN_FILE, OUT_FILE);
  49.        ...
  50.        procedure OPEN (FILE : in out FILE_TYPE; ...);
  51.        ...
  52.        procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
  53.        procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
  54.        ...
  55.     end SEQUENTIAL_IO;
  56.           
  57.  
  58. In order to define sequential input-output for a  given  element  type,  an
  59. instantiation  of  this  generic  unit,  with  the  given  type  as  actual
  60. parameter,  must  be  declared.   The  resulting   package   contains   the
  61. declaration  of  a file type (called FILE_TYPE) for files of such elements,
  62. as well as the operations applicable to these  files,  such  as  the  OPEN,
  63. READ, and WRITE procedures.
  64.  
  65.  
  66. Input-output  for  direct  access  files  is  likewise defined by a generic
  67. package called DIRECT_IO.  Input-output in human-readable form  is  defined
  68. by the (nongeneric) package TEXT_IO.
  69.  
  70.  
  71. Before input or output operations can be performed on a file, the file must
  72. first be associated with an external file.  While such an association is in
  73. effect,  the  file is said to be open, and otherwise the file is said to be
  74. closed.
  75.  
  76.  
  77. The language does not define what  happens  to  external  files  after  the
  78. completion  of the main program (in particular, if corresponding files have
  79. not  been  closed).   The  effect  of  input-output  for  access  types  is
  80. implementation-dependent.
  81.  
  82.  
  83. An open file has a current mode, which is a value of one of the enumeration
  84. types
  85.  
  86.     type FILE_MODE is (IN_FILE, INOUT_FILE, OUT_FILE);  --  for DIRECT_IO
  87.     type FILE_MODE is (IN_FILE, OUT_FILE);              --  for SEQUENTIAL_IO and TEXT_IO
  88.  
  89.  
  90. These  values correspond respectively to the cases where only reading, both
  91. reading and writing, or only writing are to be performed.  The  mode  of  a
  92. file can be changed.
  93.  
  94.  
  95. Several  file  management  operations  are common to the three input-output
  96. packages.  These operations are described in section 14.2.1 for  sequential
  97. and  direct files.  Any additional effects concerning text input-output are
  98. described in section 14.3.1.
  99.  
  100.  
  101. The exceptions that can be raised by a call of an  input-output  subprogram
  102. are  all  defined  in  the  package IO_EXCEPTIONS;  the situations in which
  103. they can be raised are described, either following the description  of  the
  104. subprogram  (and  in  section  14.4), or in Appendix F in the case of error
  105. situations that are implementation-dependent.
  106.  
  107. Notes:
  108.  
  109.  
  110. Each instantiation of the  generic  packages  SEQUENTIAL_IO  and  DIRECT_IO
  111. declares  a  different  type  FILE_TYPE;   in the case of TEXT_IO, the type
  112. FILE_TYPE is unique.
  113.  
  114.  
  115. A bidirectional device  can  often  be  modeled  as  two  sequential  files
  116. associated  with the device, one of mode IN_FILE, and one of mode OUT_FILE.
  117. An implementation may restrict the number of files that may  be  associated
  118. with a given external file.  The effect of sharing an external file in this
  119. way by several file objects is implementation-dependent.
  120.  
  121.  
  122. References:   create  procedure  14.2.1,  current  index 14.2, current size
  123. 14.2, delete procedure 14.2.1, direct access 14.2,  direct  file  procedure
  124. 14.2,  direct_io  package  14.1 14.2, enumeration type 3.5.1, exception 11,
  125. file mode 14.2.3,  generic  instantiation  12.3,  index  14.2,  input  file
  126. 14.2.2,  io_exceptions package 14.5, open file 14.1, open procedure 14.2.1,
  127. output  file  14.2.2,  read  procedure  14.2.4,  sequential  access   14.2,
  128. sequential file 14.2, sequential input-output 14.2.2, sequential_io package
  129. 14.2 14.2.2, string 3.6.3, text_io package 14.3, write procedure 14.2.4
  130.  
  131. > 14.2  Sequential and Direct Files
  132.  
  133.  
  134. Two  kinds  of access to external files are defined:  sequential access and
  135. direct access.  The corresponding file types and the associated  operations
  136. are  provided  by the generic packages SEQUENTIAL_IO and DIRECT_IO.  A file
  137. object to be used for sequential access is called a  sequential  file,  and
  138. one to be used for direct access is called a direct file.
  139.  
  140.  
  141. For  sequential access, the file is viewed as a sequence of values that are
  142. transferred in the order of their appearance (as produced by the program or
  143. by the environment).  When the file is opened,  transfer  starts  from  the
  144. beginning of the file.
  145.  
  146.  
  147. For  direct  access,  the  file  is  viewed  as a set of elements occupying
  148. consecutive positions in linear order;  a value can be  transferred  to  or
  149. from  an  element of the file at any selected position.  The position of an
  150. element is specified by its index, which is a number, greater than zero, of
  151. the implementation-defined integer type COUNT.  The first element, if  any,
  152. has  index  one;   the  index  of  the  last element, if any, is called the
  153. current size;  the current size is zero if  there  are  no  elements.   The
  154. current size is a property of the external file.
  155.  
  156.  
  157. An  open  direct  file has a current index, which is the index that will be
  158. used by the next read or write operation.  When a direct  file  is  opened,
  159. the  current  index is set to one.  The current index of a direct file is a
  160. property of a file object, not of an external file.
  161.  
  162.  
  163. All three file modes are allowed for direct files.  The only allowed  modes
  164. for sequential files are the modes IN_FILE and OUT_FILE.
  165.  
  166.  
  167. References:  count type 14.3, file mode 14.1, in_file 14.1, out_file 14.1
  168.  
  169. > 14.2.1  File Management
  170.  
  171.  
  172. The  procedures  and  functions  described  in this section provide for the
  173. control of external files;  their declarations are repeated in each of  the
  174. three  packages  for  sequential,  direct, and text input-output.  For text
  175. input-output, the  procedures  CREATE,  OPEN,  and  RESET  have  additional
  176. effects described in section 14.3.1.
  177.  
  178.  
  179.     procedure CREATE(FILE : in out FILE_TYPE;
  180.                      MODE : in FILE_MODE := DEFAULT_MODE;
  181.                      NAME : in STRING := "";
  182.                      FORM : in STRING := "");
  183.  
  184.  
  185.           Establishes  a  new  external file, with the given name and form,
  186.           and associates this external file with the given file.  The given
  187.           file is left open.  The current mode of the given file is set  to
  188.           the  given  access  mode.   The  default  access mode is the mode
  189.           OUT_FILE for sequential and text input-output;  it  is  the  mode
  190.           INOUT_FILE  for direct input-output.  For direct access, the size
  191.           of the created file is implementation-dependent.  A  null  string
  192.           for  NAME specifies an external file that is not accessible after
  193.           the completion of the main program (a temporary  file).   A  null
  194.           string  for  FORM specifies the use of the default options of the
  195.           implementation for the external file.
  196.  
  197.  
  198.           The exception STATUS_ERROR is raised if the given file is already
  199.           open.  The exception NAME_ERROR is raised if the string given  as
  200.           NAME  does not allow the identification of an external file.  The
  201.           exception USE_ERROR is raised if, for  the  specified  mode,  the
  202.           environment  does  not  support creation of an external file with
  203.           the given name (in the absence of NAME_ERROR) and form.
  204.  
  205.  
  206.     procedure OPEN(FILE : in out FILE_TYPE;
  207.                    MODE : in FILE_MODE;
  208.                    NAME : in STRING;
  209.                    FORM : in STRING := "");
  210.  
  211.  
  212.           Associates the given file with an existing external  file  having
  213.           the  given  name and form, and sets the current mode of the given
  214.           file to the given mode.  The given file is left open.
  215.  
  216.  
  217.           The exception STATUS_ERROR is raised if the given file is already
  218.           open.  The exception NAME_ERROR is raised if the string given  as
  219.           NAME  does  not allow the identification of an external file;  in
  220.           particular, this exception is raised if no external file with the
  221.           given name exists.  The exception USE_ERROR is raised if, for the
  222.           specified mode, the environment does not support opening  for  an
  223.           external  file with the given name (in the absence of NAME_ERROR)
  224.           and form.
  225.  
  226.  
  227.     procedure CLOSE(FILE : in out FILE_TYPE);
  228.  
  229.  
  230.           Severs the association between the given file and its  associated
  231.           external file.  The given file is left closed.
  232.  
  233.  
  234.           The  exception  STATUS_ERROR  is  raised if the given file is not
  235.           open.
  236.  
  237.  
  238.     procedure DELETE(FILE : in out FILE_TYPE);
  239.  
  240.  
  241.           Deletes the external file associated with the  given  file.   The
  242.           given file is closed, and the external file ceases to exist.
  243.  
  244.  
  245.           The  exception  STATUS_ERROR  is  raised if the given file is not
  246.           open.  The exception USE_ERROR is raised if (as fully defined  in
  247.           Appendix F) deletion of the external file is not supported by the
  248.           environment.
  249.  
  250.  
  251.     procedure RESET(FILE : in out FILE_TYPE; MODE : in FILE_MODE);
  252.     procedure RESET(FILE : in out FILE_TYPE);
  253.  
  254.  
  255.           Resets  the  given  file  so  that reading from or writing to its
  256.           elements can be restarted from the beginning  of  the  file;   in
  257.           particular,  for  direct access this means that the current index
  258.           is set to one.  If a MODE parameter is supplied, the current mode
  259.           of the given file is set to the given mode.
  260.  
  261.  
  262.           The exception STATUS_ERROR is raised if the  file  is  not  open.
  263.           The  exception  USE_ERROR  is  raised if the environment does not
  264.           support resetting  for  the  external  file  and,  also,  if  the
  265.           environment  does not support resetting to the specified mode for
  266.           the external file.
  267.  
  268.  
  269.     function MODE(FILE : in FILE_TYPE) return FILE_MODE;
  270.  
  271.  
  272.           Returns the current mode of the given file.
  273.  
  274.  
  275.           The exception STATUS_ERROR is raised if the file is not open.
  276.  
  277.  
  278.     function NAME(FILE : in FILE_TYPE) return STRING;
  279.  
  280.  
  281.           Returns a string which  uniquely  identifies  the  external  file
  282.           currently associated with the given file (and may thus be used in
  283.           an   OPEN  operation).   If  an  environment  allows  alternative
  284.           specifications of the  name  (for  example,  abbreviations),  the
  285.           string  returned  by  the  function  should  correspond to a full
  286.           specification of the name.
  287.  
  288.  
  289.           The exception STATUS_ERROR is raised if the  given  file  is  not
  290.           open.
  291.  
  292.  
  293.     function FORM(FILE : in FILE_TYPE) return STRING;
  294.  
  295.  
  296.           Returns   the   form  string  for  the  external  file  currently
  297.           associated  with  the  given  file.   If  an  environment  allows
  298.           alternative    specifications   of   the   form   (for   example,
  299.           abbreviations using default options), the string returned by  the
  300.           function  should  correspond to a full specification (that is, it
  301.           should  indicate  explicitly  all  options  selected,   including
  302.           default options).
  303.  
  304.  
  305.           The  exception  STATUS_ERROR  is  raised if the given file is not
  306.           open.
  307.  
  308.  
  309.     function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
  310.  
  311.  
  312.           Returns TRUE if the file is open (that is, if  it  is  associated
  313.           with an external file), otherwise returns FALSE.
  314.  
  315.  
  316. References:  current mode 14.1, current size 14.1, closed file 14.1, direct
  317. access  14.2, external file 14.1, file 14.1, file_mode type 14.1, file_type
  318. type 14.1, form string 14.1, inout_file  14.2.4,  mode  14.1,  name  string
  319. 14.1,   name_error   exception   14.4,   open  file  14.1,  out_file  14.1,
  320. status_error exception 14.4, use_error exception 14.4
  321.  
  322. > 14.2.2  Sequential Input-Output
  323.  
  324.  
  325. The operations available for sequential input and output are  described  in
  326. this  section.   The  exception  STATUS_ERROR  is  raised  if  any of these
  327. operations is attempted for a file that is not open.
  328.  
  329.  
  330.     procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
  331.  
  332.  
  333.           Operates on a file of mode IN_FILE.  Reads an  element  from  the
  334.           given  file,  and  returns  the value of this element in the ITEM
  335.           parameter.
  336.  
  337.  
  338.           The exception MODE_ERROR is raised if the mode  is  not  IN_FILE.
  339.           The exception END_ERROR is raised if no more elements can be read
  340.           from  the  given file.  The exception DATA_ERROR is raised if the
  341.           element read cannot  be  interpreted  as  a  value  of  the  type
  342.           ELEMENT_TYPE;  however, an implementation is allowed to omit this
  343.           check if performing the check is too complex.
  344.  
  345.  
  346.     procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
  347.  
  348.  
  349.           Operates on a file of mode OUT_FILE.  Writes the value of ITEM to
  350.           the given file.
  351.  
  352.  
  353.           The  exception  MODE_ERROR is raised if the mode is not OUT_FILE.
  354.           The exception USE_ERROR is raised if the capacity of the external
  355.           file is exceeded.
  356.  
  357.  
  358.     function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
  359.  
  360.  
  361.           Operates on a file of mode IN_FILE.   Returns  TRUE  if  no  more
  362.           elements  can  be  read  from  the given file;  otherwise returns
  363.           FALSE.
  364.  
  365.  
  366.           The exception MODE_ERROR is raised if the mode is not IN_FILE.
  367.  
  368.  
  369. References:  data_error exception 14.4, element  14.1,  element_type  14.1,
  370. end_error  exception  14.4,  external file 14.1, file 14.1, file mode 14.1,
  371. file_type 14.1, in_file 14.1, mode_error  exception  14.4,  out_file  14.1,
  372. status_error exception 14.4, use_error exception 14.4
  373.  
  374. > 14.2.3  Specification of the Package Sequential_IO
  375.  
  376.  
  377.     with IO_EXCEPTIONS;
  378.     generic
  379.        type ELEMENT_TYPE is private;
  380.     package SEQUENTIAL_IO is
  381.  
  382.        type FILE_TYPE is limited private;
  383.  
  384.        type FILE_MODE is (IN_FILE, OUT_FILE);
  385.  
  386.        -- File management
  387.  
  388.        procedure CREATE(FILE : in out FILE_TYPE;
  389.                         MODE : in FILE_MODE := OUT_FILE;
  390.                         NAME : in STRING := "";
  391.                         FORM : in STRING := "");
  392.  
  393.        procedure OPEN  (FILE : in out FILE_TYPE;
  394.                         MODE : in FILE_MODE;
  395.                         NAME : in STRING;
  396.                         FORM : in STRING := "");
  397.  
  398.        procedure CLOSE (FILE : in out FILE_TYPE);
  399.        procedure DELETE(FILE : in out FILE_TYPE);
  400.        procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
  401.        procedure RESET (FILE : in out FILE_TYPE);
  402.  
  403.        function MODE   (FILE : in FILE_TYPE) return FILE_MODE;
  404.        function NAME   (FILE : in FILE_TYPE) return STRING;
  405.        function FORM   (FILE : in FILE_TYPE) return STRING;
  406.  
  407.        function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
  408.  
  409.        -- Input and output operations
  410.  
  411.        procedure READ  (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
  412.        procedure WRITE (FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
  413.  
  414.        function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
  415.  
  416.        -- Exceptions
  417.  
  418.        STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
  419.        MODE_ERROR   : exception renames IO_EXCEPTIONS.MODE_ERROR;
  420.        NAME_ERROR   : exception renames IO_EXCEPTIONS.NAME_ERROR;
  421.        USE_ERROR    : exception renames IO_EXCEPTIONS.USE_ERROR;
  422.        DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
  423.        END_ERROR    : exception renames IO_EXCEPTIONS.END_ERROR;
  424.        DATA_ERROR   : exception renames IO_EXCEPTIONS.DATA_ERROR;
  425.  
  426.     private
  427.        -- implementation-dependent
  428.     end SEQUENTIAL_IO;
  429.  
  430.  
  431. References:   close  procedure  14.2.1, create procedure 14.2.1, data_error
  432. exception 14.4,  delete  procedure  14.2.1,  device_error  exception  14.4,
  433. end_error  exception  14.4,  end_of_file  function  14.2.2, file_mode 14.1,
  434. file_type 14.1, form function 14.2.1,  in_file  14.1,  io_exceptions  14.4,
  435. is_open  function  14.2.1, mode function 14.2.1, mode_error exception 14.4,
  436. name function 14.2.1, name_error exception  14.4,  open  procedure  14.2.1,
  437. out_file 14.1, read procedure 14.2.2, reset procedure 14.2.1, sequential_io
  438. package 14.2 14.2.2, status_error exception 14.4, use_error exception 14.4,
  439. write procedure 14.2.2,
  440.  
  441. > 14.2.4  Direct Input-Output
  442.  
  443.  
  444. The  operations available for direct input and output are described in this
  445. section.  The exception STATUS_ERROR is raised if any of  these  operations
  446. is attempted for a file that is not open.
  447.  
  448.  
  449.     procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE;
  450.                                         FROM : in  POSITIVE_COUNT);
  451.     procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
  452.  
  453.  
  454.           Operates on a file of mode IN_FILE or INOUT_FILE.  In the case of
  455.           the  first  form, sets the current index of the given file to the
  456.           index value given by the parameter FROM.  Then (for  both  forms)
  457.           returns,  in  the  parameter ITEM, the value of the element whose
  458.           position in the given file is specified by the current  index  of
  459.           the file;  finally, increases the current index by one.
  460.  
  461.  
  462.           The  exception MODE_ERROR is raised if the mode of the given file
  463.           is OUT_FILE.  The exception END_ERROR is raised if the  index  to
  464.           be  used  exceeds  the  size of the external file.  The exception
  465.           DATA_ERROR is raised if the element read cannot be interpreted as
  466.           a value of the type ELEMENT_TYPE;  however, an implementation  is
  467.           allowed  to  omit  this  check  if  performing  the  check is too
  468.           complex.
  469.  
  470.  
  471.     procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE;
  472.                                          TO   : in POSITIVE_COUNT);
  473.     procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
  474.  
  475.  
  476.           Operates on a file of mode INOUT_FILE or OUT_FILE.  In  the  case
  477.           of  the first form, sets the index of the given file to the index
  478.           value given by the parameter TO.  Then (for both forms) gives the
  479.           value of the parameter ITEM to the element whose position in  the
  480.           given  file  is  specified  by  the  current  index  of the file;
  481.           finally, increases the current index by one.
  482.  
  483.  
  484.           The exception MODE_ERROR is raised if the mode of the given  file
  485.           is IN_FILE.  The exception USE_ERROR is raised if the capacity of
  486.           the external file is exceeded.
  487.  
  488.  
  489.     procedure SET_INDEX(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
  490.  
  491.  
  492.           Operates  on  a  file of any mode.  Sets the current index of the
  493.           given file to the given index value (which may exceed the current
  494.           size of the file).
  495.  
  496.  
  497.     function INDEX(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  498.  
  499.  
  500.           Operates on a file of any mode.  Returns the current index of the
  501.           given file.
  502.  
  503.  
  504.     function SIZE(FILE : in FILE_TYPE) return COUNT;
  505.  
  506.  
  507.           Operates on a file of any mode.  Returns the current size of  the
  508.           external file that is associated with the given file.
  509.  
  510.  
  511.     function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
  512.  
  513.  
  514.           Operates  on  a file of mode IN_FILE or INOUT_FILE.  Returns TRUE
  515.           if the current index exceeds  the  size  of  the  external  file;
  516.           otherwise returns FALSE.
  517.  
  518.  
  519.           The  exception MODE_ERROR is raised if the mode of the given file
  520.           is OUT_FILE.
  521.  
  522.  
  523. References:  count type  14.2,  current  index  14.2,  current  size  14.2,
  524. data_error  exception  14.4,  element  14.1,  element_type  14.1, end_error
  525. exception 14.4, external file 14.1, file 14.1, file  mode  14.1,  file_type
  526. 14.1, in_file 14.1, index 14.2, inout_file 14.1, mode_error exception 14.4,
  527. open file 14.1, positive_count 14.3, status_error exception 14.4, use_error
  528. exception 14.4
  529.  
  530. > 14.2.5  Specification of the Package Direct_IO
  531.  
  532.  
  533.     with IO_EXCEPTIONS;
  534.     generic
  535.        type ELEMENT_TYPE is private;
  536.     package DIRECT_IO is
  537.  
  538.        type FILE_TYPE is limited private;
  539.  
  540.        type    FILE_MODE is (IN_FILE, INOUT_FILE, OUT_FILE);
  541.        type    COUNT     is range 0 .. IMPLEMENTATION_DEFINED;
  542.        subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
  543.  
  544.        -- File management
  545.  
  546.        procedure CREATE(FILE : in out FILE_TYPE;
  547.                         MODE : in FILE_MODE := INOUT_FILE;
  548.                         NAME : in STRING := "";
  549.                         FORM : in STRING := "");
  550.  
  551.        procedure OPEN  (FILE : in out FILE_TYPE;
  552.                         MODE : in FILE_MODE;
  553.                         NAME : in STRING;
  554.                         FORM : in STRING := "");
  555.  
  556.        procedure CLOSE (FILE : in out FILE_TYPE);
  557.        procedure DELETE(FILE : in out FILE_TYPE);
  558.        procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
  559.        procedure RESET (FILE : in out FILE_TYPE);
  560.  
  561.        function MODE   (FILE : in FILE_TYPE) return FILE_MODE;
  562.        function NAME   (FILE : in FILE_TYPE) return STRING;
  563.        function FORM   (FILE : in FILE_TYPE) return STRING;
  564.  
  565.        function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
  566.  
  567.        -- Input and output operations
  568.  
  569.        procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE; FROM : POSITIVE_COUNT);
  570.        procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
  571.  
  572.        procedure WRITE(FILE : in FILE_TYPE; ITEM : in  ELEMENT_TYPE; TO : POSITIVE_COUNT);
  573.        procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
  574.  
  575.        procedure SET_INDEX(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
  576.  
  577.        function INDEX(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  578.        function SIZE (FILE : in FILE_TYPE) return COUNT;
  579.  
  580.        function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
  581.  
  582.        -- Exceptions
  583.  
  584.        STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
  585.        MODE_ERROR   : exception renames IO_EXCEPTIONS.MODE_ERROR;
  586.        NAME_ERROR   : exception renames IO_EXCEPTIONS.NAME_ERROR;
  587.        USE_ERROR    : exception renames IO_EXCEPTIONS.USE_ERROR;
  588.        DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
  589.        END_ERROR    : exception renames IO_EXCEPTIONS.END_ERROR;
  590.        DATA_ERROR   : exception renames IO_EXCEPTIONS.DATA_ERROR;
  591.  
  592.     private
  593.        -- implementation-dependent
  594.     end DIRECT_IO;
  595.  
  596.  
  597. References  close  procedure  14.2.1,  count  type  14.2,  create procedure
  598. 14.2.1, data_error exception 14.4, default_mode  14.2.5,  delete  procedure
  599. 14.2.1,   device_error   exception  14.4,  element_type  14.2.4,  end_error
  600. exception 14.4, end_of_file function 14.2.4,  file_mode  14.2.5,  file_type
  601. 14.2.4,  form  function  14.2.1,  in_file  14.2.4,  index  function 14.2.4,
  602. inout_file 14.2.4 14.2.1,  io_exceptions  package  14.4,  is_open  function
  603. 14.2.1,  mode  function  14.2.1,  mode_error  exception 14.4, name function
  604. 14.2.1, name_error exception 14.4, open procedure 14.2.1, out_file  14.2.1,
  605. read  procedure  14.2.4,  set_index procedure 14.2.4, size function 14.2.4,
  606. status_error exception 14.4,  use_error  exception  14.4,  write  procedure
  607. 14.2.4 14.2.1
  608.  
  609. > 14.3  Text Input-Output
  610.  
  611.  
  612. This  section  describes the package TEXT_IO, which provides facilities for
  613. input and output in human-readable form.  Each  file  is  read  or  written
  614. sequentially,  as  a  sequence  of  characters grouped into lines, and as a
  615. sequence of lines grouped into pages.  The specification of the package  is
  616. given below in section 14.3.10.
  617.  
  618.  
  619. The  facilities  for  file  management  given above, in sections 14.2.1 and
  620. 14.2.2, are available for text input-output.  In place of READ  and  WRITE,
  621. however,  there  are  procedures  GET and PUT that input values of suitable
  622. types from text files,  and  output  values  to  them.   These  values  are
  623. provided  to  the  PUT procedures, and returned by the GET procedures, in a
  624. parameter ITEM.  Several overloaded procedures of these  names  exist,  for
  625. different  types of ITEM.  These GET procedures analyze the input sequences
  626. of  characters  as  lexical  elements  (see  Chapter  2)  and  return   the
  627. corresponding  values;   the  PUT  procedures  output  the  given values as
  628. appropriate lexical elements.  Procedures GET and PUT  are  also  available
  629. that  input  and  output  individual characters treated as character values
  630. rather than as lexical elements.
  631.  
  632.  
  633. In addition to the procedures GET and PUT for numeric and enumeration types
  634. of ITEM that operate on text files, analogous procedures are provided  that
  635. read  from  and  write  to  a  parameter  of type STRING.  These procedures
  636. perform the same analysis and composition of character sequences  as  their
  637. counterparts which have a file parameter.
  638.  
  639.  
  640. For  all  GET  and  PUT procedures that operate on text files, and for many
  641. other subprograms, there are forms with and without a file parameter.  Each
  642. such GET procedure operates on an input file, and each such  PUT  procedure
  643. operates  on an output file.  If no file is specified, a default input file
  644. or a default output file is used.
  645.  
  646.  
  647. At the beginning of program execution the default input  and  output  files
  648. are  the  so-called  standard  input  file and standard output file.  These
  649. files are open, have respectively the current modes IN_FILE  and  OUT_FILE,
  650. and   are   associated  with  two  implementation-defined  external  files.
  651. Procedures are provided to change the current default input  file  and  the
  652. current default output file.
  653.  
  654.  
  655. From a logical point of view, a text file is a sequence of pages, a page is
  656. a  sequence of lines, and a line is a sequence of characters;  the end of a
  657. line is marked by a line terminator;  the end of a page is  marked  by  the
  658. combination of a line terminator immediately followed by a page terminator;
  659. and  the  end  of  a file is marked by the combination of a line terminator
  660. immediately followed by a page  terminator  and  then  a  file  terminator.
  661. Terminators  are  generated  during  output;  either by calls of procedures
  662. provided expressly for that  purpose;   or  implicitly  as  part  of  other
  663. operations, for example, when a bounded line length, a bounded page length,
  664. or both, have been specified for a file.
  665.  
  666.  
  667. The  actual  nature of terminators is not defined by the language and hence
  668. depends on the implementation.   Although  terminators  are  recognized  or
  669. generated   by  certain  of  the  procedures  that  follow,  they  are  not
  670. necessarily implemented  as  characters  or  as  sequences  of  characters.
  671. Whether  they  are  characters  (and  if  so  which ones) in any particular
  672. implementation need not concern a user who neither explicitly  outputs  nor
  673. explicitly  inputs  control  characters.   The effect of input or output of
  674. control characters (other than horizontal tabulation) is not defined by the
  675. language.
  676.  
  677.  
  678. The characters of a line are numbered, starting from one;  the number of  a
  679. character  is  called  its  column number.  For a line terminator, a column
  680. number is also defined:  it is one more than the number  of  characters  in
  681. the  line.   The  lines  of  a page, and the pages of a file, are similarly
  682. numbered.  The current column number is  the  column  number  of  the  next
  683. character or line terminator to be transferred.  The current line number is
  684. the  number  of the current line.  The current page number is the number of
  685. the current page.  These numbers are values of the  subtype  POSITIVE_COUNT
  686. of  the type COUNT (by convention, the value zero of the type COUNT is used
  687. to indicate special conditions).
  688.  
  689.     type COUNT is range 0 .. implementation_defined;
  690.     subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
  691.  
  692.  
  693. For an output file, a maximum line length can be specified  and  a  maximum
  694. page  length  can  be specified.  If a value to be output cannot fit on the
  695. current line, for a specified maximum line  length,  then  a  new  line  is
  696. automatically  started  before  the value is output;  if, further, this new
  697. line cannot fit on the current page, for a specified maximum  page  length,
  698. then  a  new  page  is  automatically  started  before the value is output.
  699. Functions are provided to determine the maximum line length and the maximum
  700. page length.  When a file is opened with mode  OUT_FILE,  both  values  are
  701. zero:  by convention, this means that the line lengths and page lengths are
  702. unbounded.   (Consequently,  output  consists  of  a  single  line  if  the
  703. subprograms for explicit control of line and page structure are not  used.)
  704. The constant UNBOUNDED is provided for this purpose.
  705.  
  706.  
  707. References:  count type 14.3.10, default current input file 14.3.2, default
  708. current  output  file  14.3.2, external file 14.1, file 14.1, get procedure
  709. 14.3.5, in_file 14.1, out_file 14.1, put  procedure  14.3.5,  read  14.2.2,
  710. sequential  access  14.1,  standard input file 14.3.2, standard output file
  711. 14.3.2
  712.  
  713. > 14.3.1  File Management
  714.  
  715.  
  716. The only allowed file modes for  text  files  are  the  modes  IN_FILE  and
  717. OUT_FILE.   The  subprograms  given  in  section  14.2.1 for the control of
  718. external files, and the function END_OF_FILE given in  section  14.2.2  for
  719. sequential  input-output, are also available for text files.  There is also
  720. a version of END_OF_FILE that refers to the  current  default  input  file.
  721. For text files, the procedures have the following additional effects:
  722.  
  723.  
  724.   -  For the procedures CREATE and OPEN:  After opening a  file  with  mode
  725.      OUT_FILE, the page length and line length are unbounded (both have the
  726.      conventional  value  zero).  After opening a file with mode IN_FILE or
  727.      OUT_FILE, the current column, current line, and current  page  numbers
  728.      are set to one.
  729.  
  730.  
  731.   -  For the procedure CLOSE:  If the file has the current  mode  OUT_FILE,
  732.      has the effect of calling NEW_PAGE, unless the current page is already
  733.      terminated; then outputs a file terminator.
  734.  
  735.  
  736.   -  For the procedure RESET:  If the file has the current  mode  OUT_FILE,
  737.      has the effect of calling NEW_PAGE, unless the current page is already
  738.      terminated;   then outputs a file terminator.  If the new file mode is
  739.      OUT_FILE, the page and line lengths are unbounded.  For all modes, the
  740.      current column, line, and page numbers are set to one.
  741.  
  742.  
  743. The exception MODE_ERROR is raised by the procedure RESET upon  an  attempt
  744. to change the mode of a file that is either the current default input file,
  745. or the current default output file.
  746.  
  747.  
  748. References:   create  procedure 14.2.1, current column number 14.3, current
  749. default input file 14.3, current line  number  14.3,  current  page  number
  750. 14.3, end_of_file 14.3, external file 14.1, file 14.1, file mode 14.1, file
  751. terminator 14.3, in_file 14.1, line length 14.3, mode_error exception 14.4,
  752. open  procedure  14.2.1,  out_file  14.1, page length 14.3, reset procedure
  753. 14.2.1
  754.  
  755. > 14.3.2  Default Input and Output Files
  756.  
  757.  
  758. The following subprograms provide for the control of the particular default
  759. files that are used when a file parameter is omitted from  a  GET,  PUT  or
  760. other operation of text input-output described below.
  761.  
  762.  
  763.     procedure SET_INPUT(FILE : in FILE_TYPE);
  764.  
  765.  
  766.           Operates  on  a  file  of mode IN_FILE.  Sets the current default
  767.           input file to FILE.
  768.  
  769.  
  770.           The exception STATUS_ERROR is raised if the  given  file  is  not
  771.           open.   The  exception  MODE_ERROR  is  raised if the mode of the
  772.           given file is not IN_FILE.
  773.  
  774.  
  775.     procedure SET_OUTPUT(FILE : in FILE_TYPE);
  776.  
  777.  
  778.           Operates on a file of mode OUT_FILE.  Sets  the  current  default
  779.           output file to FILE.
  780.  
  781.  
  782.           The  exception  STATUS_ERROR  is  raised if the given file is not
  783.           open.  The exception MODE_ERROR is raised  if  the  mode  of  the
  784.           given file is not OUT_FILE.
  785.  
  786.  
  787.     function STANDARD_INPUT return FILE_TYPE;
  788.  
  789.  
  790.           Returns the standard input file (see 14.3).
  791.  
  792.  
  793.     function STANDARD_OUTPUT return FILE_TYPE;
  794.  
  795.  
  796.           Returns the standard output file (see 14.3).
  797.  
  798.  
  799.     function CURRENT_INPUT return FILE_TYPE;
  800.  
  801.  
  802.           Returns the current default input file.
  803.  
  804.  
  805.     function CURRENT_OUTPUT return FILE_TYPE;
  806.  
  807.  
  808.           Returns the current default output file.
  809.  
  810. Note:
  811.  
  812.  
  813. The  standard input and the standard output files cannot be opened, closed,
  814. reset,  or  deleted,  because  the  parameter  FILE  of  the  corresponding
  815. procedures has the mode in out.
  816.  
  817.  
  818. References:   current default file 14.3, default file 14.3, file_type 14.1,
  819. get procedure 14.3.5, mode_error  exception  14.4,  put  procedure  14.3.5,
  820. status_error exception 14.4
  821.  
  822. > 14.3.3  Specification of Line and Page Lengths
  823.  
  824.  
  825. The  subprograms  described in this section are concerned with the line and
  826. page structure of a file of mode OUT_FILE.  They operate either on the file
  827. given as the first parameter, or, in the absence of such a file  parameter,
  828. on the current default output file.  They provide for output of text with a
  829. specified  maximum  line  length  or page length.  In these cases, line and
  830. page terminators are output implicitly and automatically when needed.  When
  831. line  and  page  lengths  are  unbounded  (that  is,  when  they  have  the
  832. conventional  value zero), as in the case of a newly opened file, new lines
  833. and new pages are only started when explicitly called for.
  834.  
  835.  
  836. In all cases, the exception STATUS_ERROR is raised if the file to  be  used
  837. is  not open; the exception MODE_ERROR is raised if the mode of the file is
  838. not OUT_FILE.
  839.  
  840.  
  841.     procedure SET_LINE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
  842.     procedure SET_LINE_LENGTH(TO   : in COUNT);
  843.  
  844.  
  845.           Sets the maximum line length of the specified output file to  the
  846.           number  of  characters  specified  by  TO.  The value zero for TO
  847.           specifies an unbounded line length.
  848.  
  849.  
  850.           The exception USE_ERROR is raised if the specified line length is
  851.           inappropriate for the associated external file.
  852.  
  853.  
  854.     procedure SET_PAGE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
  855.     procedure SET_PAGE_LENGTH(TO   : in COUNT);
  856.  
  857.  
  858.           Sets the maximum page length of the specified output file to  the
  859.           number of lines specified by TO.  The value zero for TO specifies
  860.           an unbounded page length.
  861.  
  862.  
  863.           The exception USE_ERROR is raised if the specified page length is
  864.           inappropriate for the associated external file.
  865.  
  866.  
  867.     function LINE_LENGTH(FILE : in FILE_TYPE) return COUNT;
  868.     function LINE_LENGTH return COUNT;
  869.  
  870.  
  871.           Returns  the  maximum line length currently set for the specified
  872.           output file, or zero if the line length is unbounded.
  873.  
  874.  
  875.     function PAGE_LENGTH(FILE : in FILE_TYPE) return COUNT;
  876.     function PAGE_LENGTH return COUNT;
  877.  
  878.  
  879.           Returns the maximum page length currently set for  the  specified
  880.           output file, or zero if the page length is unbounded.
  881.  
  882.  
  883. References:   count  type  14.3, current default output file 14.3, external
  884. file 14.1, file 14.1, file_type 14.1, line 14.3,  line  length  14.3,  line
  885. terminator  14.3,  maximum  line  length  14.3,  maximum  page length 14.3,
  886. mode_error exception 14.4, open file 14.1, out_file 14.1, page  14.3,  page
  887. length  14.3,  page terminator 14.3, status_error exception 14.4, unbounded
  888. page length 14.3, use_error exception 14.4
  889.  
  890. > 14.3.4  Operations on Columns, Lines, and Pages
  891.  
  892.  
  893. The subprograms described in this section provide for explicit  control  of
  894. line  and  page  structure;   they  operate either on the file given as the
  895. first parameter, or, in the absence  of  such  a  file  parameter,  on  the
  896. appropriate   (input  or  output)  current  default  file.   The  exception
  897. STATUS_ERROR is raised by any of these subprograms if the file to  be  used
  898. is not open.
  899.  
  900.  
  901.     procedure NEW_LINE(FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
  902.     procedure NEW_LINE(SPACING : in POSITIVE_COUNT := 1);
  903.  
  904.           Operates on a file of mode OUT_FILE.
  905.  
  906.  
  907.           For  a  SPACING  of  one:  Outputs a line terminator and sets the
  908.           current column number to one.  Then increments the  current  line
  909.           number by one, except in the case that the current line number is
  910.           already  greater  than or equal to the maximum page length, for a
  911.           bounded page length;  in that case a page terminator  is  output,
  912.           the  current  page  number is incremented by one, and the current
  913.           line number is set to one.
  914.  
  915.  
  916.           For a SPACING greater than one, the above actions  are  performed
  917.           SPACING times.
  918.  
  919.  
  920.           The  exception  MODE_ERROR is raised if the mode is not OUT_FILE.
  921.  
  922.  
  923.     procedure SKIP_LINE(FILE    : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
  924.     procedure SKIP_LINE(SPACING : in POSITIVE_COUNT := 1);
  925.  
  926.  
  927.           Operates on a file of mode IN_FILE.
  928.  
  929.  
  930.           For a SPACING of one:  Reads and discards all characters until  a
  931.           line  terminator  has been read, and then sets the current column
  932.           number to  one.   If  the  line  terminator  is  not  immediately
  933.           followed  by  a  page  terminator,  the  current  line  number is
  934.           incremented  by  one.   Otherwise,  if  the  line  terminator  is
  935.           immediately   followed  by  a  page  terminator,  then  the  page
  936.           terminator is skipped, the current page number is incremented  by
  937.           one, and the current line number is set to one.
  938.  
  939.  
  940.           For  a  SPACING greater than one, the above actions are performed
  941.           SPACING times.
  942.  
  943.  
  944.           The exception MODE_ERROR is raised if the mode  is  not  IN_FILE.
  945.           The exception END_ERROR is raised if an attempt is made to read a
  946.           file terminator.
  947.  
  948.  
  949.     function END_OF_LINE(FILE : in FILE_TYPE) return BOOLEAN;
  950.     function END_OF_LINE return BOOLEAN;
  951.  
  952.  
  953.           Operates  on  a  file  of  mode IN_FILE.  Returns TRUE if  a line
  954.           terminator or a  file  terminator  is  next;   otherwise  returns
  955.           FALSE.
  956.  
  957.  
  958.           The exception MODE_ERROR is raised if the mode is not IN_FILE.
  959.  
  960.  
  961.     procedure NEW_PAGE(FILE : in FILE_TYPE);
  962.     procedure NEW_PAGE;
  963.  
  964.  
  965.           Operates  on  a file of mode OUT_FILE.  Outputs a line terminator
  966.           if the current line is not terminated, or if the current page  is
  967.           empty  (that  is, if the current column and line numbers are both
  968.           equal to one).  Then outputs a page terminator, which  terminates
  969.           the  current  page.  Adds one to the current page number and sets
  970.           the current column and line numbers to one.
  971.  
  972.  
  973.           The exception MODE_ERROR is raised if the mode is  not  OUT_FILE.
  974.  
  975.  
  976.     procedure SKIP_PAGE(FILE: in FILE_TYPE);
  977.     procedure SKIP_PAGE;
  978.  
  979.  
  980.           Operates  on  a  file  of  mode  IN_FILE.  Reads and discards all
  981.           characters and line terminators until a page terminator has  been
  982.           read.   Then  adds  one  to the current page number, and sets the
  983.           current column and line numbers to one.
  984.  
  985.  
  986.           The exception MODE_ERROR is raised if the mode  is  not  IN_FILE.
  987.           The exception END_ERROR is raised if an attempt is made to read a
  988.           file terminator.
  989.  
  990.  
  991.     function END_OF_PAGE(FILE : in FILE_TYPE) return BOOLEAN;
  992.     function END_OF_PAGE return BOOLEAN;
  993.  
  994.  
  995.           Operates  on  a  file  of  mode  IN_FILE.   Returns  TRUE  if the
  996.           combination of a line terminator and a page terminator  is  next,
  997.           or if a file terminator is next;  otherwise returns FALSE.
  998.  
  999.  
  1000.           The exception MODE_ERROR is raised if the mode is not IN_FILE.
  1001.  
  1002.  
  1003.     function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
  1004.     function END_OF_FILE return BOOLEAN;
  1005.  
  1006.  
  1007.           Operates  on  a  file  of  mode  IN_FILE.  Returns TRUE if a file
  1008.           terminator is next, or if the combination of a line, a page,  and
  1009.           a file terminator is next;  otherwise returns FALSE.
  1010.  
  1011.  
  1012.           The exception MODE_ERROR is raised if the mode is not IN_FILE.
  1013.  
  1014.  
  1015. The  following  subprograms provide for the control of the current position
  1016. of reading or writing in a file.  In all cases, the  default  file  is  the
  1017. current output file.
  1018.  
  1019.  
  1020.     procedure SET_COL(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
  1021.     procedure SET_COL(TO   : in POSITIVE_COUNT);
  1022.  
  1023.  
  1024.           If the file mode is OUT_FILE:
  1025.  
  1026.  
  1027.                If  the  value  specified  by TO is greater than the current
  1028.                column number, outputs spaces, adding  one  to  the  current
  1029.                column  number  after  each  space, until the current column
  1030.                number equals the specified value.  If the  value  specified
  1031.                by  TO  is  equal  to the current column number, there is no
  1032.                effect.  If the value specified  by  TO  is  less  than  the
  1033.                current  column  number,  has the effect of calling NEW_LINE
  1034.                (with a spacing of one), then outputs (TO - 1)  spaces,  and
  1035.                sets the current column number to the specified value.
  1036.  
  1037.  
  1038.                The  exception LAYOUT_ERROR is raised if the value specified
  1039.                by TO exceeds LINE_LENGTH when the line  length  is  bounded
  1040.                (that  is,  when  it  does  not  have the conventional value
  1041.                zero).
  1042.  
  1043.  
  1044.  
  1045.           If the file mode is IN_FILE:
  1046.  
  1047.  
  1048.                Reads   (and   discards)   individual    characters,    line
  1049.                terminators,  and page terminators, until the next character
  1050.                to be read  has  a  column  number  that  equals  the  value
  1051.                specified  by  TO;  there is no effect if the current column
  1052.                number already  equals  this  value.   Each  transfer  of  a
  1053.                character  or terminator maintains the current column, line,
  1054.                and page numbers in the same way as  a  GET  procedure  (see
  1055.                14.3.5).   (Short  lines  will  be  skipped  until a line is
  1056.                reached  that  has  a  character  at  the  specified  column
  1057.                position.)
  1058.  
  1059.  
  1060.                The  exception  END_ERROR is raised if an attempt is made to
  1061.                read a file terminator.
  1062.  
  1063.  
  1064.     procedure SET_LINE(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
  1065.     procedure SET_LINE(TO   : in POSITIVE_COUNT);
  1066.  
  1067.  
  1068.           If the file mode is OUT_FILE:
  1069.  
  1070.  
  1071.                If the value specified by TO is  greater  than  the  current
  1072.                line  number,  has the effect of repeatedly calling NEW_LINE
  1073.                (with a spacing of  one),  until  the  current  line  number
  1074.                equals the specified value.  If the value specified by TO is
  1075.                equal  to  the  current line number, there is no effect.  If
  1076.                the value specified by TO is  less  than  the  current  line
  1077.                number,  has  the  effect  of calling NEW_PAGE followed by a
  1078.                call of NEW_LINE with a spacing equal to (TO - 1).
  1079.  
  1080.  
  1081.                The exception LAYOUT_ERROR is raised if the value  specified
  1082.                by  TO  exceeds  PAGE_LENGTH when the page length is bounded
  1083.                (that is, when it  does  not  have  the  conventional  value
  1084.                zero).
  1085.  
  1086.  
  1087.           If the mode is IN_FILE:
  1088.  
  1089.  
  1090.                Has  the  effect  of  repeatedly  calling  SKIP_LINE (with a
  1091.                spacing of one), until the current line  number  equals  the
  1092.                value  specified  by  TO;  there is no effect if the current
  1093.                line number already equals this value.  (Short pages will be
  1094.                skipped until a page is reached  that  has  a  line  at  the
  1095.                specified line position.)
  1096.  
  1097.  
  1098.                The  exception  END_ERROR is raised if an attempt is made to
  1099.                read a file terminator.
  1100.  
  1101.  
  1102.     function COL(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  1103.     function COL return POSITIVE_COUNT;
  1104.  
  1105.  
  1106.           Returns the current column number.
  1107.  
  1108.  
  1109.           The exception LAYOUT_ERROR  is  raised  if  this  number  exceeds
  1110.           COUNT'LAST.
  1111.  
  1112.  
  1113.     function LINE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  1114.     function LINE return POSITIVE_COUNT;
  1115.  
  1116.  
  1117.           Returns the current line number.
  1118.  
  1119.  
  1120.           The  exception  LAYOUT_ERROR  is  raised  if  this number exceeds
  1121.           COUNT'LAST.
  1122.  
  1123.  
  1124.     function PAGE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  1125.     function PAGE return POSITIVE_COUNT;
  1126.  
  1127.  
  1128.           Returns the current page number.
  1129.  
  1130.  
  1131.           The exception LAYOUT_ERROR  is  raised  if  this  number  exceeds
  1132.           COUNT'LAST.
  1133.  
  1134.  
  1135. The  column  number,  line  number,  or  page  number are allowed to exceed
  1136. COUNT'LAST (as a consequence of the input or output  of  sufficiently  many
  1137. characters,  lines,  or pages).  These events do not cause any exception to
  1138. be raised.  However, a call of COL, LINE,  or  PAGE  raises  the  exception
  1139. LAYOUT_ERROR if the corresponding number exceeds COUNT'LAST.
  1140.  
  1141. Note:
  1142.  
  1143.  
  1144. A  page terminator is always skipped whenever the preceding line terminator
  1145. is skipped.  An implementation  may  represent  the  combination  of  these
  1146. terminators  by a single character, provided that it is properly recognized
  1147. at input.
  1148.  
  1149.  
  1150. References:  current column number 14.3, current default file 14.3, current
  1151. line number 14.3, current page number 14.3, end_error exception 14.4,  file
  1152. 14.1,   file   terminator   14.3,   get  procedure  14.3.5,  in_file  14.1,
  1153. layout_error exception 14.4, line 14.3, line number 14.3,  line  terminator
  1154. 14.3,  maximum page length 14.3, mode_error exception 14.4, open file 14.1,
  1155. page 14.3, page length 14.3, page terminator  14.3,  positive  count  14.3,
  1156. status_error exception 14.4
  1157.  
  1158. > 14.3.5  Get and Put Procedures
  1159.  
  1160.  
  1161. The  procedures  GET  and  PUT  for  items  of the types CHARACTER, STRING,
  1162. numeric types, and enumeration types are described in subsequent  sections.
  1163. Features  of  these  procedures  that are common to most of these types are
  1164. described in this section.  The GET and PUT procedures for  items  of  type
  1165. CHARACTER  and  STRING  deal with individual character values;  the GET and
  1166. PUT procedures for numeric and enumeration types treat the items as lexical
  1167. elements.
  1168.  
  1169.  
  1170. All procedures GET and PUT have forms with a file parameter, written first.
  1171. Where this parameter is omitted, the appropriate (input or output)  current
  1172. default file is understood to be specified.  Each procedure GET operates on
  1173. a  file  of  mode  IN_FILE.   Each procedure PUT operates on a file of mode
  1174. OUT_FILE.
  1175.  
  1176.  
  1177. All procedures GET and PUT maintain the  current  column,  line,  and  page
  1178. numbers of the specified file:  the effect of each of these procedures upon
  1179. these  numbers  is  the resultant of the effects of individual transfers of
  1180. characters and of individual  output  or  skipping  of  terminators.   Each
  1181. transfer of a character adds one to the current column number.  Each output
  1182. of  a line terminator sets the current column number to one and adds one to
  1183. the current line number.   Each  output  of  a  page  terminator  sets  the
  1184. current  column  and  line  numbers to one and adds one to the current page
  1185. number.  For input, each skipping of a line  terminator  sets  the  current
  1186. column  number  to  one  and  adds  one  to  the current line number;  each
  1187. skipping of a page terminator sets the current column and line  numbers  to
  1188. one  and adds one to the current page number.  Similar considerations apply
  1189. to the procedures GET_LINE, PUT_LINE, and SET_COL.
  1190.  
  1191.  
  1192. Several GET and PUT procedures, for numeric  and  enumeration  types,  have
  1193. format parameters which specify field lengths;  these parameters are of the
  1194. nonnegative subtype FIELD of the type INTEGER.
  1195.  
  1196.  
  1197. Input-output  of  enumeration  values  uses the syntax of the corresponding
  1198. lexical elements.  Any GET procedure for  an  enumeration  type  begins  by
  1199. skipping  any  leading  blanks, or line or page terminators;  a blank being
  1200. defined as a space or a horizontal tabulation character.  Next,  characters
  1201. are  input  only so long as the sequence input is an initial sequence of an
  1202. identifier or of a character literal (in particular, input  ceases  when  a
  1203. line  terminator  is  encountered).   The character or line terminator that
  1204. causes input to cease remains available for subsequent input.
  1205.  
  1206.  
  1207. For a numeric type, the GET  procedures  have  a  format  parameter  called
  1208. WIDTH.   If  the  value given for this parameter is zero, the GET procedure
  1209. proceeds in the same manner as for enumeration types, but using the  syntax
  1210. of  numeric literals instead of that of enumeration literals.  If a nonzero
  1211. value is given, then exactly WIDTH characters are input, or the  characters
  1212. up to a line terminator, whichever comes first;  any skipped leading blanks
  1213. are  included  in  the  count.   The syntax used for numeric literals is an
  1214. extended syntax that allows a leading sign (but no intervening  blanks,  or
  1215. line or page terminators).
  1216.  
  1217.  
  1218. Any PUT procedure, for an item of a numeric or an enumeration type, outputs
  1219. the  value  of  the  item  as  a  numeric literal, identifier, or character
  1220. literal, as appropriate.  This is preceded by leading spaces if required by
  1221. the format parameters WIDTH or FORE (as described in later  sections),  and
  1222. then  a  minus  sign  for  a  negative value;  for an enumeration type, the
  1223. spaces follow instead of leading.  The format given for a PUT procedure  is
  1224. overridden if it is insufficiently wide.
  1225.  
  1226.  
  1227. Two  further  cases  arise  for  PUT procedures for numeric and enumeration
  1228. types, if the line length of the specified output file is bounded (that is,
  1229. if it does not have  the  conventional  value  zero).   If  the  number  of
  1230. characters  to  be  output  does not exceed the maximum line length, but is
  1231. such that they cannot fit on the current line, starting  from  the  current
  1232. column,  then (in effect) NEW_LINE is called (with a spacing of one) before
  1233. output of the item.  Otherwise, if the number  of  characters  exceeds  the
  1234. maximum  line  length,  then  the  exception  LAYOUT_ERROR is raised and no
  1235. characters are output.
  1236.  
  1237.  
  1238. The exception  STATUS_ERROR  is  raised  by  any  of  the  procedures  GET,
  1239. GET_LINE,  PUT,  and  PUT_LINE  if  the  file  to be used is not open.  The
  1240. exception MODE_ERROR is raised by the procedures GET and  GET_LINE  if  the
  1241. mode  of the file to be used is not IN_FILE;  and by the procedures PUT and
  1242. PUT_LINE, if the mode is not OUT_FILE.
  1243.  
  1244.  
  1245. The exception END_ERROR is raised by a GET procedure if an attempt is  made
  1246. to  skip  a  file  terminator.  The exception DATA_ERROR is raised by a GET
  1247. procedure  if  the  sequence  finally  input  is  not  a  lexical   element
  1248. corresponding  to the type, in particular if no characters were input;  for
  1249. this test, leading blanks are ignored;  for an item of a numeric type, when
  1250. a sign is input, this rule applies to the succeeding numeric literal.   The
  1251. exception  LAYOUT_ERROR  is  raised  by  a  PUT procedure that outputs to a
  1252. parameter  of  type  STRING,  if  the  length  of  the  actual  string   is
  1253. insufficient for the output of the item.
  1254.  
  1255.  
  1256. Examples:
  1257.  
  1258.  
  1259. In  the examples, here and in sections 14.3.7 and 14.3.8, the string quotes
  1260. and the lower case letter b are not transferred:  they are  shown  only  to
  1261. reveal the layout and spaces.
  1262.  
  1263.     N : INTEGER;
  1264.        ...
  1265.     GET(N);
  1266.  
  1267.     -- Characters at input       Sequence input       Value of N
  1268.  
  1269.     --      bb-12535b            -12535               -12535
  1270.     --      bb12_535E1b           12_535E1             125350
  1271.     --      bb12_535E;            12_535E              (none) DATA_ERROR raised
  1272.  
  1273.  
  1274. Example of overridden width parameter:
  1275.  
  1276.     PUT(ITEM => -23, WIDTH => 2);  --  "-23"
  1277.  
  1278.  
  1279. References:   blank  14.3.9, column number 14.3, current default file 14.3,
  1280. data_error exception  14.4,  end_error  exception  14.4,  file  14.1,  fore
  1281. 14.3.8,   get   procedure   14.3.6  14.3.7  14.3.8  14.3.9,  in_file  14.1,
  1282. layout_error exception  14.4,  line  number  14.1,  line  terminator  14.1,
  1283. maximum  line  length  14.3, mode 14.1, mode_error exception 14.4, new_file
  1284. procedure 14.3.4, out_file 14.1, page number 14.1,  page  terminator  14.1,
  1285. put  procedure  14.3.6 14.3.7 14.3.8 14.3.9, skipping 14.3.7 14.3.8 14.3.9,
  1286. status_error exception 14.4, width 14.3.5 14.3.7 14.3.9
  1287.  
  1288. > 14.3.6  Input-Output of Characters and Strings
  1289.  
  1290.  
  1291. For an item of type CHARACTER the following procedures are provided:
  1292.  
  1293.  
  1294.     procedure GET(FILE : in FILE_TYPE; ITEM : out CHARACTER);
  1295.     procedure GET(ITEM : out CHARACTER);
  1296.  
  1297.  
  1298.           After skipping any line terminators  and  any  page  terminators,
  1299.           reads  the  next  character  from  the  specified  input file and
  1300.           returns the value of this character in the out parameter ITEM.
  1301.  
  1302.  
  1303.           The exception END_ERROR is raised if an attempt is made to skip a
  1304.           file terminator.
  1305.  
  1306.  
  1307.     procedure PUT(FILE : in FILE_TYPE; ITEM : in CHARACTER);
  1308.     procedure PUT(ITEM : in CHARACTER);
  1309.  
  1310.  
  1311.           If the line length of the specified output file is bounded  (that
  1312.           is,  does  not have the conventional value zero), and the current
  1313.           column number exceeds it, has the effect of calling NEW_LINE with
  1314.           a  spacing  of  one.   Then,  or  otherwise,  outputs  the  given
  1315.           character to the file.
  1316.  
  1317.  
  1318. For an item of type STRING the following procedures are provided:
  1319.  
  1320.  
  1321.     procedure GET(FILE : in FILE_TYPE; ITEM : out STRING);
  1322.     procedure GET(ITEM : out STRING);
  1323.  
  1324.  
  1325.           Determines  the  length  of  the  given  string and attempts that
  1326.           number of GET operations for successive characters of the  string
  1327.           (in particular, no operation is performed if the string is null).
  1328.  
  1329.  
  1330.     procedure PUT(FILE : in FILE_TYPE; ITEM : in STRING);
  1331.     procedure PUT(ITEM : in STRING);
  1332.  
  1333.  
  1334.           Determines  the  length  of  the  given  string and attempts that
  1335.           number of PUT operations for successive characters of the  string
  1336.           (in particular, no operation is performed if the string is null).
  1337.  
  1338.  
  1339.     procedure GET_LINE(FILE : in FILE_TYPE; ITEM : out STRING; LAST : out NATURAL);
  1340.     procedure GET_LINE(ITEM : out STRING;   LAST : out NATURAL);
  1341.  
  1342.  
  1343.           Replaces   successive  characters  of  the  specified  string  by
  1344.           successive  characters  read  from  the  specified  input   file.
  1345.           Reading  stops  if  the end of the line is met, in which case the
  1346.           procedure SKIP_LINE is then called (in effect) with a spacing  of
  1347.           one;   reading  also  stops  if  the  end  of  the string is met.
  1348.           Characters not replaced are left undefined.
  1349.  
  1350.  
  1351.           If characters are read, returns in LAST the index value such that
  1352.           ITEM(LAST) is the last character replaced (the index of the first
  1353.           character replaced is ITEM'FIRST).  If no  characters  are  read,
  1354.           returns  in LAST an index value that is one less than ITEM'FIRST.
  1355.  
  1356.  
  1357.           The exception END_ERROR is raised if an attempt is made to skip a
  1358.           file terminator.
  1359.  
  1360.  
  1361.     procedure PUT_LINE(FILE : in FILE_TYPE; ITEM : in STRING);
  1362.     procedure PUT_LINE(ITEM : in STRING);
  1363.  
  1364.  
  1365.           Calls the procedure PUT  for  the  given  string,  and  then  the
  1366.           procedure NEW_LINE with a spacing of one.
  1367.  
  1368. Notes:
  1369.  
  1370.  
  1371. In  a  literal  string  parameter  of  PUT,  the  enclosing  string bracket
  1372. characters are not output.  Each doubled string bracket  character  in  the
  1373. enclosed  string  is  output  as  a  single  string bracket character, as a
  1374. consequence of the rule for string literals (see 2.6).
  1375.  
  1376.  
  1377. A string read by GET or written by PUT can extend over several lines.
  1378.  
  1379.  
  1380. References:  current column number 14.3,  end_error  exception  14.4,  file
  1381. 14.1,  file  terminator  14.3, get procedure 14.3.5, line 14.3, line length
  1382. 14.3, new_line  procedure  14.3.4,  page  terminator  14.3,  put  procedure
  1383. 14.3.4, skipping 14.3.5
  1384.  
  1385. > 14.3.7  Input-Output for Integer Types
  1386.  
  1387.  
  1388. The  following  procedures  are  defined in the generic package INTEGER_IO.
  1389. This must be instantiated for the appropriate integer  type  (indicated  by
  1390. NUM in the specification).
  1391.  
  1392.  
  1393. Values   are  output  as  decimal  or  based  literals,  without  underline
  1394. characters or exponent, and preceded by a  minus  sign  if  negative.   The
  1395. format  (which includes any leading spaces and minus sign) can be specified
  1396. by an optional field width parameter.  Values of widths of fields in output
  1397. formats are of the nonnegative integer subtype FIELD.  Values of bases  are
  1398. of the integer subtype NUMBER_BASE.
  1399.  
  1400.     subtype NUMBER_BASE is INTEGER range 2 .. 16;
  1401.  
  1402.  
  1403. The  default  field  width  and  base  to  be used by output procedures are
  1404. defined by the following variables that are declared in the generic package
  1405. INTEGER_IO:
  1406.  
  1407.     DEFAULT_WIDTH : FIELD := NUM'WIDTH;
  1408.     DEFAULT_BASE  : NUMBER_BASE := 10;
  1409.  
  1410.  
  1411. The following procedures are provided:
  1412.  
  1413.  
  1414.     procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
  1415.     procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
  1416.  
  1417.  
  1418.           If the value of the parameter WIDTH is zero,  skips  any  leading
  1419.           blanks,  line terminators, or page terminators, then reads a plus
  1420.           or a minus sign if present, then reads according to the syntax of
  1421.           an integer literal (which may be a based literal).  If a  nonzero
  1422.           value  of  WIDTH  is  supplied, then exactly WIDTH characters are
  1423.           input, or the characters (possibly none) up to a line terminator,
  1424.           whichever comes first;  any skipped leading blanks  are  included
  1425.           in the count.
  1426.  
  1427.  
  1428.           Returns,  in  the  parameter  ITEM,  the  value  of type NUM that
  1429.           corresponds to the sequence input.
  1430.  
  1431.  
  1432.           The exception DATA_ERROR is raised if the sequence input does not
  1433.           have the required syntax or if the value obtained is not  of  the
  1434.           subtype NUM.
  1435.  
  1436.  
  1437.     procedure PUT(FILE  : in FILE_TYPE;
  1438.                   ITEM  : in NUM;
  1439.                   WIDTH : in FIELD := DEFAULT_WIDTH;
  1440.                   BASE  : in NUMBER_BASE := DEFAULT_BASE);
  1441.  
  1442.     procedure PUT(ITEM  : in NUM;
  1443.                   WIDTH : in FIELD := DEFAULT_WIDTH;
  1444.                   BASE  : in NUMBER_BASE := DEFAULT_BASE);
  1445.  
  1446.  
  1447.           Outputs  the  value  of the parameter ITEM as an integer literal,
  1448.           with no underlines, no exponent, and  no  leading  zeros  (but  a
  1449.           single zero for the value zero), and a preceding minus sign for a
  1450.           negative value.
  1451.  
  1452.  
  1453.           If  the  resulting  sequence of characters to be output has fewer
  1454.           than WIDTH characters, then leading spaces are  first  output  to
  1455.           make up the difference.
  1456.  
  1457.  
  1458.           Uses the syntax for decimal literal if the parameter BASE has the
  1459.           value   ten   (either   explicitly   or   through  DEFAULT_BASE);
  1460.           otherwise, uses the syntax for based literal, with any letters in
  1461.           upper case.
  1462.  
  1463.  
  1464.     procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
  1465.  
  1466.  
  1467.           Reads an integer value from the beginning of  the  given  string,
  1468.           following  the  same  rules  as  the  GET procedure that reads an
  1469.           integer value from a file, but treating the end of the string  as
  1470.           a  file terminator.  Returns, in the parameter ITEM, the value of
  1471.           type NUM that corresponds to the sequence input.  Returns in LAST
  1472.           the index value such that FROM(LAST) is the last character  read.
  1473.  
  1474.  
  1475.           The exception DATA_ERROR is raised if the sequence input does not
  1476.           have  the  required syntax or if the value obtained is not of the
  1477.           subtype NUM.
  1478.  
  1479.  
  1480.     procedure PUT(TO   : out STRING;
  1481.                   ITEM : in NUM;
  1482.                   BASE : in NUMBER_BASE := DEFAULT_BASE);
  1483.  
  1484.  
  1485.           Outputs the value of the parameter  ITEM  to  the  given  string,
  1486.           following the same rule as for output to a file, using the length
  1487.           of the given string as the value for WIDTH.
  1488.  
  1489.  
  1490. Examples:
  1491.  
  1492.     package INT_IO is new INTEGER_IO(SMALL_INT); use INT_IO;
  1493.     -- default format used at instantiation, DEFAULT_WIDTH = 4, DEFAULT_BASE = 10
  1494.  
  1495.     PUT(126);                            -- "b126"
  1496.     PUT(-126, 7);                        -- "bbb-126"
  1497.     PUT(126, WIDTH => 13, BASE => 2);    -- "bbb2#1111110#"
  1498.  
  1499.  
  1500. References:   based literal 2.4.2, blank 14.3.5, data_error exception 14.4,
  1501. decimal literal 2.4.1, field subtype 14.3.5, file_type 14.1, get  procedure
  1502. 14.3.5,  integer_io  package  14.3.10,  integer  literal  2.4, layout_error
  1503. exception 14.4,  line  terminator  14.3,  put  procedure  14.3.5,  skipping
  1504. 14.3.5, width 14.3.5
  1505.  
  1506. > 14.3.8  Input-Output for Real Types
  1507.  
  1508.  
  1509. The  following  procedures are defined in the generic packages FLOAT_IO and
  1510. FIXED_IO, which must be instantiated for the appropriate floating point  or
  1511. fixed point type respectively (indicated by NUM in the specifications).
  1512.  
  1513.  
  1514. Values  are  output  as decimal literals without underline characters.  The
  1515. format of each value output consists of a FORE field, a decimal  point,  an
  1516. AFT field, and (if a nonzero EXP parameter is supplied) the letter E and an
  1517. EXP field.  The two possible formats thus correspond to:
  1518.  
  1519.     FORE  .  AFT
  1520.  
  1521.  
  1522. and to:
  1523.  
  1524.     FORE  .  AFT  E  EXP
  1525.  
  1526.  
  1527. without  any  spaces  between  these  fields.   The  FORE field may include
  1528. leading spaces, and a minus sign  for  negative  values.    The  AFT  field
  1529. includes only decimal digits (possibly with trailing zeros).  The EXP field
  1530. includes  the  sign (plus or minus) and the exponent (possibly with leading
  1531. zeros).
  1532.  
  1533.  
  1534. For floating point types, the default lengths of these fields  are  defined
  1535. by  the  following  variables  that  are  declared  in  the generic package
  1536. FLOAT_IO:
  1537.  
  1538.     DEFAULT_FORE : FIELD := 2;
  1539.     DEFAULT_AFT  : FIELD := NUM'DIGITS-1;
  1540.     DEFAULT_EXP  : FIELD := 3;
  1541.  
  1542.  
  1543. For fixed point types, the default lengths of these fields are  defined  by
  1544. the  following variables that are declared in the generic package FIXED_IO:
  1545.  
  1546.     DEFAULT_FORE : FIELD := NUM'FORE;
  1547.     DEFAULT_AFT  : FIELD := NUM'AFT;
  1548.     DEFAULT_EXP  : FIELD := 0;
  1549.  
  1550.  
  1551. The following procedures are provided:
  1552.  
  1553.  
  1554.     procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
  1555.     procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
  1556.  
  1557.  
  1558.           If the value of the parameter WIDTH is zero,  skips  any  leading
  1559.           blanks,  line terminators, or page terminators, then reads a plus
  1560.           or a minus sign if present, then reads according to the syntax of
  1561.           a real literal (which may be a  based  literal).   If  a  nonzero
  1562.           value  of  WIDTH  is  supplied, then exactly WIDTH characters are
  1563.           input, or the characters (possibly none) up to a line terminator,
  1564.           whichever comes first;  any skipped leading blanks  are  included
  1565.           in the count.
  1566.  
  1567.  
  1568.           Returns,  in  the  parameter  ITEM,  the  value  of type NUM that
  1569.           corresponds to the sequence input.
  1570.  
  1571.  
  1572.           The exception DATA_ERROR is raised if the sequence input does not
  1573.           have the required syntax or if the value obtained is not  of  the
  1574.           subtype NUM.
  1575.  
  1576.  
  1577.     procedure PUT(FILE : in FILE_TYPE;
  1578.                   ITEM : in NUM;
  1579.                   FORE : in FIELD := DEFAULT_FORE;
  1580.                   AFT  : in FIELD := DEFAULT_AFT;
  1581.                   EXP  : in FIELD := DEFAULT_EXP);
  1582.  
  1583.     procedure PUT(ITEM : in NUM;
  1584.                   FORE : in FIELD := DEFAULT_FORE;
  1585.                   AFT  : in FIELD := DEFAULT_AFT;
  1586.                   EXP  : in FIELD := DEFAULT_EXP);
  1587.  
  1588.  
  1589.           Outputs the value of the parameter ITEM as a decimal literal with
  1590.           the  format  defined  by  FORE,  AFT  and  EXP.   If the value is
  1591.           negative, a minus sign is included in the integer part.   If  EXP
  1592.           has  the  value  zero,  then the integer part to be output has as
  1593.           many digits as are needed to represent the integer  part  of  the
  1594.           value  of  ITEM, overriding FORE if necessary, or consists of the
  1595.           digit zero if the value of ITEM has no integer part.
  1596.  
  1597.  
  1598.           If EXP has a value greater than zero, then the integer part to be
  1599.           output has a single digit, which is nonzero except for the  value
  1600.           0.0 of ITEM.
  1601.  
  1602.  
  1603.           In  both  cases,  however,  if  the integer part to be output has
  1604.           fewer than  FORE  characters,  including  any  minus  sign,  then
  1605.           leading  spaces  are first output to make up the difference.  The
  1606.           number of digits of the fractional part is given by  AFT,  or  is
  1607.           one  if  AFT  equals  zero.   The  value  is rounded;  a value of
  1608.           exactly one half in the last place may be rounded  either  up  or
  1609.           down.
  1610.  
  1611.  
  1612.           If EXP has the value zero, there is no exponent part.  If EXP has
  1613.           a  value  greater  than zero, then the exponent part to be output
  1614.           has as many digits as are needed to represent the  exponent  part
  1615.           of  the  value  of ITEM (for which a single digit integer part is
  1616.           used), and includes an initial  sign (plus  or  minus).   If  the
  1617.           exponent  part  to  be  output  has  fewer  than  EXP characters,
  1618.           including the sign, then leading zeros  precede  the  digits,  to
  1619.           make  up the difference.  For the value 0.0 of ITEM, the exponent
  1620.           has the value zero.
  1621.  
  1622.  
  1623.     procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
  1624.  
  1625.  
  1626.           Reads a real value  from  the  beginning  of  the  given  string,
  1627.           following  the  same  rule as the GET procedure that reads a real
  1628.           value from a file, but treating the end of the string as  a  file
  1629.           terminator.   Returns,  in  the parameter ITEM, the value of type
  1630.           NUM that corresponds to the sequence input.  Returns in LAST  the
  1631.           index value such that FROM(LAST) is the last character read.
  1632.  
  1633.  
  1634.           The exception DATA_ERROR is raised if the sequence input does not
  1635.           have  the required syntax, or if the value obtained is not of the
  1636.           subtype NUM.
  1637.  
  1638.  
  1639.     procedure PUT(TO   : out STRING;
  1640.                   ITEM : in NUM;
  1641.                   AFT  : in FIELD := DEFAULT_AFT;
  1642.                   EXP  : in INTEGER := DEFAULT_EXP);
  1643.  
  1644.  
  1645.           Outputs the value of the parameter  ITEM  to  the  given  string,
  1646.           following  the  same  rule as for output to a file, using a value
  1647.           for FORE such that the  sequence  of  characters  output  exactly
  1648.           fills the string, including any leading spaces.
  1649.  
  1650.  
  1651. Examples:
  1652.  
  1653.     package REAL_IO is new FLOAT_IO(REAL); use REAL_IO;
  1654.     -- default format used at instantiation, DEFAULT_EXP = 3
  1655.  
  1656.     X : REAL := -123.4567;  --  digits 8      (see 3.5.7)
  1657.  
  1658.     PUT(X); -- default format                   "-1.2345670E+02"
  1659.     PUT(X, FORE => 5, AFT => 3, EXP => 2);  --  "bbb-1.235E+2"
  1660.     PUT(X, 5, 3, 0);                        --  "b-123.457"
  1661.  
  1662. Note:
  1663.  
  1664.  
  1665. For  an item with a positive value, if output to a string exactly fills the
  1666. string without leading spaces, then output of  the  corresponding  negative
  1667. value will raise LAYOUT_ERROR.
  1668.  
  1669.  
  1670. References:   aft  attribute  3.5.10,  based  literal  2.4.2, blank 14.3.5,
  1671. data_error exception 14.3.5, decimal literal 2.4.1, field  subtype  14.3.5,
  1672. file_type 14.1, fixed_io package 14.3.10, floating_io package 14.3.10, fore
  1673. attribute   3.5.10,   get   procedure  14.3.5,  layout_error  14.3.5,  line
  1674. terminator 14.3.5, put procedure 14.3.5, real literal 2.4, skipping 14.3.5,
  1675. width 14.3.5
  1676.  
  1677. > 14.3.9  Input-Output for Enumeration Types
  1678.  
  1679.  
  1680. The following procedures are defined in the generic package ENUMERATION_IO,
  1681. which must be instantiated for the appropriate enumeration type  (indicated
  1682. by ENUM in the specification).
  1683.  
  1684.  
  1685. Values are output using either upper or lower case letters for identifiers.
  1686. This  is  specified  by the parameter SET, which is of the enumeration type
  1687. TYPE_SET.
  1688.  
  1689.     type TYPE_SET is (LOWER_CASE, UPPER_CASE);
  1690.  
  1691.  
  1692. The format (which includes any trailing spaces)  can  be  specified  by  an
  1693. optional  field  width  parameter.  The default field width and letter case
  1694. are defined by the following variables that are  declared  in  the  generic
  1695. package ENUMERATION_IO:
  1696.  
  1697.     DEFAULT_WIDTH   : FIELD := 0;
  1698.     DEFAULT_SETTING : TYPE_SET := UPPER_CASE;
  1699.  
  1700.  
  1701. The following procedures are provided:
  1702.  
  1703.  
  1704.     procedure GET(FILE : in FILE_TYPE; ITEM : out ENUM);
  1705.     procedure GET(ITEM : out ENUM);
  1706.  
  1707.  
  1708.           After  skipping  any  leading  blanks,  line terminators, or page
  1709.           terminators, reads an identifier according to the syntax of  this
  1710.           lexical   element   (lower   and   upper  case  being  considered
  1711.           equivalent), or a character literal according to  the  syntax  of
  1712.           this  lexical  element  (including the apostrophes).  Returns, in
  1713.           the parameter ITEM, the value of type ENUM  that  corresponds  to
  1714.           the sequence input.
  1715.  
  1716.  
  1717.           The exception DATA_ERROR is raised if the sequence input does not
  1718.           have  the  required  syntax,  or  if  the identifier or character
  1719.           literal does not correspond to a value of the subtype ENUM.
  1720.  
  1721.  
  1722.     procedure PUT(FILE  : in FILE_TYPE;
  1723.                   ITEM  : in ENUM;
  1724.                   WIDTH : in FIELD := DEFAULT_WIDTH;
  1725.                   SET   : in TYPE_SET := DEFAULT_SETTING);
  1726.  
  1727.     procedure PUT(ITEM  : in ENUM;
  1728.                   WIDTH : in FIELD := DEFAULT_WIDTH;
  1729.                   SET   : in TYPE_SET := DEFAULT_SETTING);
  1730.  
  1731.  
  1732.           Outputs the value of the parameter ITEM as an enumeration literal
  1733.           (either an identifier or  a  character  literal).   The  optional
  1734.           parameter  SET indicates whether lower case or upper case is used
  1735.           for identifiers;  it has no effect for  character  literals.   If
  1736.           the   sequence  of  characters  produced  has  fewer  than  WIDTH
  1737.           characters, then trailing spaces are finally output  to  make  up
  1738.           the difference.
  1739.  
  1740.  
  1741.     procedure GET(FROM : in STRING; ITEM : out ENUM; LAST : out POSITIVE);
  1742.  
  1743.  
  1744.           Reads  an  enumeration  value  from  the  beginning  of the given
  1745.           string, following the same rule as the GET  procedure that  reads
  1746.           an  enumeration  value  from  a file, but treating the end of the
  1747.           string as a file terminator.  Returns, in the parameter ITEM, the
  1748.           value of type  ENUM  that  corresponds  to  the  sequence  input.
  1749.           Returns  in LAST the index value such that FROM(LAST) is the last
  1750.           character read.
  1751.  
  1752.  
  1753.           The exception DATA_ERROR is raised if the sequence input does not
  1754.           have the required syntax,  or  if  the  identifier  or  character
  1755.           literal does not correspond to a value of the subtype ENUM.
  1756.  
  1757.  
  1758.     procedure PUT(TO   : out STRING;
  1759.                   ITEM : in ENUM;
  1760.                   SET  : in TYPE_SET := DEFAULT_SETTING);
  1761.  
  1762.  
  1763.           Outputs  the  value  of  the  parameter ITEM to the given string,
  1764.           following the same rule as for output to a file, using the length
  1765.           of the given string as the value for WIDTH.
  1766.  
  1767.  
  1768. Although the  specification  of  the  package  ENUMERATION_IO  would  allow
  1769. instantiation for an integer type, this is not the intended purpose of this
  1770. generic  package,  and  the effect of such instantiations is not defined by
  1771. the language.
  1772.  
  1773. Notes:
  1774.  
  1775.  
  1776. There  is  a  difference  between  PUT  defined  for  characters,  and  for
  1777. enumeration values.  Thus
  1778.  
  1779.     TEXT_IO.PUT('A');  --  outputs the character A
  1780.  
  1781.     package CHAR_IO is new TEXT_IO.ENUMERATION_IO(CHARACTER);
  1782.     CHAR_IO.PUT('A');  --  outputs the character 'A', between single quotes
  1783.  
  1784.  
  1785. The  type  BOOLEAN  is  an  enumeration  type,  hence ENUMERATION_IO can be
  1786. instantiated for this type.
  1787.  
  1788.  
  1789. References:   blank  14.3.5,  data_error  14.3.5,  enumeration_io   package
  1790. 14.3.10,  field  subtype 14.3.5, file_type 14.1, get procedure 14.3.5, line
  1791. terminator 14.3.5, put procedure 14.3.5, skipping 14.3.5, width 14.3.5
  1792.  
  1793. > 14.3.10  Specification of the Package Text_IO
  1794.  
  1795.  
  1796.     with IO_EXCEPTIONS;
  1797.     package TEXT_IO is
  1798.  
  1799.        type FILE_TYPE is limited private;
  1800.  
  1801.        type FILE_MODE is (IN_FILE, OUT_FILE);
  1802.  
  1803.        type COUNT is range 0 .. IMPLEMENTATION_DEFINED;
  1804.        subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
  1805.        UNBOUNDED : constant COUNT := 0; -- line and page length
  1806.  
  1807.        subtype FIELD       is INTEGER range 0 .. IMPLEMENTATION_DEFINED;
  1808.        subtype NUMBER_BASE is INTEGER range 2 .. 16;
  1809.  
  1810.        type TYPE_SET is (LOWER_CASE, UPPER_CASE);
  1811.  
  1812.        -- File Management
  1813.  
  1814.        procedure CREATE (FILE : in out FILE_TYPE;
  1815.                          MODE : in FILE_MODE := OUT_FILE;
  1816.                          NAME : in STRING    := "";
  1817.                          FORM : in STRING    := "");
  1818.  
  1819.        procedure OPEN   (FILE : in out FILE_TYPE;
  1820.                          MODE : in FILE_MODE;
  1821.                          NAME : in STRING;
  1822.                          FORM : in STRING := "");
  1823.  
  1824.        procedure CLOSE  (FILE : in out FILE_TYPE);
  1825.        procedure DELETE (FILE : in out FILE_TYPE);
  1826.        procedure RESET  (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
  1827.        procedure RESET  (FILE : in out FILE_TYPE);
  1828.  
  1829.        function  MODE   (FILE : in FILE_TYPE) return FILE_MODE;
  1830.        function  NAME   (FILE : in FILE_TYPE) return STRING;
  1831.        function  FORM   (FILE : in FILE_TYPE) return STRING;
  1832.  
  1833.        function  IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
  1834.  
  1835.        -- Control of default input and output files
  1836.  
  1837.        procedure SET_INPUT (FILE : in FILE_TYPE);
  1838.        procedure SET_OUTPUT(FILE : in FILE_TYPE);
  1839.  
  1840.        function STANDARD_INPUT  return FILE_TYPE;
  1841.        function STANDARD_OUTPUT return FILE_TYPE;
  1842.  
  1843.        function CURRENT_INPUT   return FILE_TYPE;
  1844.        function CURRENT_OUTPUT  return FILE_TYPE;
  1845.  
  1846.        -- Specification of line and page lengths
  1847.  
  1848.        procedure SET_LINE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
  1849.        procedure SET_LINE_LENGTH(TO : in COUNT);
  1850.  
  1851.        procedure SET_PAGE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
  1852.        procedure SET_PAGE_LENGTH(TO : in COUNT);
  1853.  
  1854.        function  LINE_LENGTH(FILE : in FILE_TYPE) return COUNT;
  1855.        function  LINE_LENGTH return COUNT;
  1856.  
  1857.        function  PAGE_LENGTH(FILE : in FILE_TYPE) return COUNT;
  1858.        function  PAGE_LENGTH return COUNT;
  1859.  
  1860.        -- Column, Line, and Page Control
  1861.  
  1862.        procedure NEW_LINE   (FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
  1863.        procedure NEW_LINE   (SPACING : in POSITIVE_COUNT := 1);
  1864.  
  1865.        procedure SKIP_LINE  (FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
  1866.        procedure SKIP_LINE  (SPACING : in POSITIVE_COUNT := 1);
  1867.  
  1868.        function  END_OF_LINE(FILE : in FILE_TYPE) return BOOLEAN;
  1869.        function  END_OF_LINE return BOOLEAN;
  1870.  
  1871.        procedure NEW_PAGE   (FILE : in FILE_TYPE);
  1872.        procedure NEW_PAGE;
  1873.  
  1874.        procedure SKIP_PAGE  (FILE : in FILE_TYPE);
  1875.        procedure SKIP_PAGE;
  1876.  
  1877.        function  END_OF_PAGE(FILE : in FILE_TYPE) return BOOLEAN;
  1878.        function  END_OF_PAGE return BOOLEAN;
  1879.  
  1880.        function  END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
  1881.        function  END_OF_FILE return BOOLEAN;
  1882.  
  1883.        procedure SET_COL (FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
  1884.        procedure SET_COL (TO   : in POSITIVE_COUNT);
  1885.  
  1886.        procedure SET_LINE(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
  1887.        procedure SET_LINE(TO   : in POSITIVE_COUNT);
  1888.  
  1889.        function COL (FILE : in FILE_TYPE) return POSITIVE_COUNT;
  1890.        function COL  return POSITIVE_COUNT;
  1891.  
  1892.        function LINE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  1893.        function LINE return POSITIVE_COUNT;
  1894.  
  1895.        function PAGE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
  1896.        function PAGE return POSITIVE_COUNT;
  1897.  
  1898.        -- Character Input-Output
  1899.  
  1900.        procedure GET(FILE : in  FILE_TYPE; ITEM : out CHARACTER);
  1901.        procedure GET(ITEM : out CHARACTER);
  1902.        procedure PUT(FILE : in  FILE_TYPE; ITEM : in CHARACTER);
  1903.        procedure PUT(ITEM : in  CHARACTER);
  1904.  
  1905.        -- String Input-Output
  1906.  
  1907.        procedure GET(FILE : in  FILE_TYPE; ITEM : out STRING);
  1908.        procedure GET(ITEM : out STRING);
  1909.        procedure PUT(FILE : in  FILE_TYPE; ITEM : in STRING);
  1910.        procedure PUT(ITEM : in  STRING);
  1911.  
  1912.        procedure GET_LINE(FILE : in  FILE_TYPE; ITEM : out STRING; LAST : out NATURAL);
  1913.        procedure GET_LINE(ITEM : out STRING; LAST : out NATURAL);
  1914.        procedure PUT_LINE(FILE : in  FILE_TYPE; ITEM : in STRING);
  1915.        procedure PUT_LINE(ITEM : in  STRING);
  1916.  
  1917.        -- Generic package for Input-Output of Integer Types
  1918.  
  1919.        generic
  1920.           type NUM is range <>;
  1921.        package INTEGER_IO is
  1922.  
  1923.           DEFAULT_WIDTH : FIELD := NUM'WIDTH;
  1924.           DEFAULT_BASE  : NUMBER_BASE := 10;
  1925.  
  1926.           procedure GET(FILE : in  FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
  1927.           procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
  1928.  
  1929.           procedure PUT(FILE  : in FILE_TYPE;
  1930.                         ITEM  : in NUM;
  1931.                         WIDTH : in FIELD := DEFAULT_WIDTH;
  1932.                         BASE  : in NUMBER_BASE := DEFAULT_BASE);
  1933.           procedure PUT(ITEM  : in NUM;
  1934.                         WIDTH : in FIELD := DEFAULT_WIDTH;
  1935.                         BASE  : in NUMBER_BASE := DEFAULT_BASE);
  1936.  
  1937.           procedure GET(FROM : in  STRING; ITEM : out NUM; LAST : out POSITIVE);
  1938.           procedure PUT(TO   : out STRING;
  1939.                         ITEM : in NUM;
  1940.                         BASE : in NUMBER_BASE := DEFAULT_BASE);
  1941.  
  1942.        end INTEGER_IO;
  1943.  
  1944.        -- Generic packages for Input-Output of Real Types
  1945.  
  1946.        generic
  1947.           type NUM is digits <>;
  1948.        package FLOAT_IO is
  1949.  
  1950.           DEFAULT_FORE : FIELD := 2;
  1951.           DEFAULT_AFT  : FIELD := NUM'DIGITS-1;
  1952.           DEFAULT_EXP  : FIELD := 3;
  1953.  
  1954.           procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
  1955.           procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
  1956.  
  1957.           procedure PUT(FILE : in FILE_TYPE;
  1958.                         ITEM : in NUM;
  1959.                         FORE : in FIELD := DEFAULT_FORE;
  1960.                         AFT  : in FIELD := DEFAULT_AFT;
  1961.                         EXP  : in FIELD := DEFAULT_EXP);
  1962.           procedure PUT(ITEM : in NUM;
  1963.                         FORE : in FIELD := DEFAULT_FORE;
  1964.                         AFT  : in FIELD := DEFAULT_AFT;
  1965.                         EXP  : in FIELD := DEFAULT_EXP);
  1966.  
  1967.           procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
  1968.           procedure PUT(TO   : out STRING;
  1969.                         ITEM : in NUM;
  1970.                         AFT  : in FIELD := DEFAULT_AFT;
  1971.                         EXP  : in FIELD := DEFAULT_EXP);
  1972.        end FLOAT_IO;
  1973.  
  1974.        generic
  1975.           type NUM is delta <>;
  1976.        package FIXED_IO is
  1977.  
  1978.           DEFAULT_FORE : FIELD := NUM'FORE;
  1979.           DEFAULT_AFT  : FIELD := NUM'AFT;
  1980.           DEFAULT_EXP  : FIELD := 0;
  1981.  
  1982.           procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
  1983.           procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
  1984.  
  1985.           procedure PUT(FILE : in FILE_TYPE;
  1986.                         ITEM : in NUM;
  1987.                         FORE : in FIELD := DEFAULT_FORE;
  1988.                         AFT  : in FIELD := DEFAULT_AFT;
  1989.                         EXP  : in FIELD := DEFAULT_EXP);
  1990.           procedure PUT(ITEM : in NUM;
  1991.                         FORE : in FIELD := DEFAULT_FORE;
  1992.                         AFT  : in FIELD := DEFAULT_AFT;
  1993.                         EXP  : in FIELD := DEFAULT_EXP);
  1994.  
  1995.           procedure GET(FROM : in  STRING; ITEM : out NUM; LAST : out POSITIVE);
  1996.           procedure PUT(TO   : out STRING;
  1997.                         ITEM : in NUM;
  1998.                         AFT  : in FIELD := DEFAULT_AFT;
  1999.                         EXP  : in FIELD := DEFAULT_EXP);
  2000.  
  2001.    end FIXED_IO;
  2002.   
  2003.        -- Generic package for Input-Output of Enumeration Types
  2004.  
  2005.        generic
  2006.           type ENUM is (<>);
  2007.        package ENUMERATION_IO is
  2008.  
  2009.           DEFAULT_WIDTH   : FIELD := 0;
  2010.           DEFAULT_SETTING : TYPE_SET := UPPER_CASE;
  2011.  
  2012.           procedure GET(FILE  : in FILE_TYPE; ITEM : out ENUM);
  2013.           procedure GET(ITEM  : out ENUM);
  2014.  
  2015.           procedure PUT(FILE  : in FILE_TYPE;
  2016.                         ITEM  : in ENUM;
  2017.                         WIDTH : in FIELD    := DEFAULT_WIDTH;
  2018.                         SET   : in TYPE_SET := DEFAULT_SETTING);
  2019.           procedure PUT(ITEM  : in ENUM;
  2020.                         WIDTH : in FIELD    := DEFAULT_WIDTH;
  2021.                         SET   : in TYPE_SET := DEFAULT_SETTING);
  2022.  
  2023.           procedure GET(FROM : in  STRING; ITEM : out ENUM; LAST : out POSITIVE);
  2024.           procedure PUT(TO   : out STRING;
  2025.                         ITEM : in  ENUM;
  2026.                         SET  : in  TYPE_SET := DEFAULT_SETTING);
  2027.        end ENUMERATION_IO;
  2028.  
  2029.        -- Exceptions
  2030.  
  2031.        STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
  2032.        MODE_ERROR   : exception renames IO_EXCEPTIONS.MODE_ERROR;
  2033.        NAME_ERROR   : exception renames IO_EXCEPTIONS.NAME_ERROR;
  2034.        USE_ERROR    : exception renames IO_EXCEPTIONS.USE_ERROR;
  2035.        DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
  2036.        END_ERROR    : exception renames IO_EXCEPTIONS.END_ERROR;
  2037.        DATA_ERROR   : exception renames IO_EXCEPTIONS.DATA_ERROR;
  2038.        LAYOUT_ERROR : exception renames IO_EXCEPTIONS.LAYOUT_ERROR;
  2039.  
  2040.     private
  2041.        -- implementation-dependent
  2042.     end TEXT_IO;
  2043.  
  2044. > 14.4  Exceptions in Input-Output
  2045.  
  2046.  
  2047. The following exceptions can be raised by  input-output  operations.   They
  2048. are  declared  in the package IO_EXCEPTIONS, defined in section 14.5;  this
  2049. package is named in the context clause for each of the  three  input-output
  2050. packages.   Only  outline  descriptions  are  given of the conditions under
  2051. which NAME_ERROR, USE_ERROR, and DEVICE_ERROR are raised;  for full details
  2052. see Appendix F.  If more than one error condition exists, the corresponding
  2053. exception that appears earliest in the following list is the  one  that  is
  2054. raised.
  2055.  
  2056.  
  2057. The  exception  STATUS_ERROR is raised by an attempt to operate upon a file
  2058. that is not open, and by an attempt to open a file that is already open.
  2059.  
  2060.  
  2061. The exception MODE_ERROR is raised by an attempt to read from, or test  for
  2062. the  end  of, a file whose current mode is OUT_FILE, and also by an attempt
  2063. to write to a file whose current mode is IN_FILE.  In the case of  TEXT_IO,
  2064. the  exception MODE_ERROR is also raised by specifying a file whose current
  2065. mode is OUT_FILE in a call of SET_INPUT, SKIP_LINE, END_OF_LINE, SKIP_PAGE,
  2066. or END_OF_PAGE;  and by specifying a file whose current mode is IN_FILE  in
  2067. a   call  of  SET_OUTPUT,  SET_LINE_LENGTH,  SET_PAGE_LENGTH,  LINE_LENGTH,
  2068. PAGE_LENGTH, NEW_LINE, or NEW_PAGE.
  2069.  
  2070.  
  2071. The exception NAME_ERROR is raised by a call  of  CREATE  or  OPEN  if  the
  2072. string given for the parameter NAME does not allow the identification of an
  2073. external  file.   For  example,  this  exception is raised if the string is
  2074. improper, or, alternatively, if either none or more than one external  file
  2075. corresponds to the string.
  2076.  
  2077.  
  2078. The  exception USE_ERROR is raised if an operation is attempted that is not
  2079. possible for reasons that depend on characteristics of the  external  file.
  2080. For  example, this exception is raised by the procedure CREATE, among other
  2081. circumstances, if the given mode is OUT_FILE  but  the  form  specifies  an
  2082. input  only  device, if the parameter FORM specifies invalid access rights,
  2083. or if an external file with the given name already exists  and  overwriting
  2084. is not allowed.
  2085.  
  2086.  
  2087. The exception DEVICE_ERROR is raised if an input-output operation cannot be
  2088. completed because of a malfunction of the underlying system.
  2089.  
  2090.  
  2091. The exception END_ERROR is raised by an attempt to skip (read past) the end
  2092. of a file.
  2093.  
  2094.  
  2095. The exception DATA_ERROR may be raised by the procedure READ if the element
  2096. read cannot be interpreted as a value of the required type.  This exception
  2097. is  also  raised by a procedure GET (defined in the package TEXT_IO) if the
  2098. input character sequence fails to satisfy the required syntax,  or  if  the
  2099. value  input  does not belong to the range of the required type or subtype.
  2100.  
  2101.  
  2102. The exception LAYOUT_ERROR is raised (in text input-output) by  COL,  LINE,
  2103. or   PAGE   if  the  value  returned  exceeds  COUNT'LAST.   The  exception
  2104. LAYOUT_ERROR is also raised on output by an attempt to set column  or  line
  2105. numbers  in  excess of specified maximum line or page lengths, respectively
  2106. (excluding the unbounded cases).  It is also raised by an attempt   to  PUT
  2107. too many characters to a string.
  2108.  
  2109.  
  2110. References:   col  function  14.3.4,  create  procedure 14.2.1, end_of_line
  2111. function 14.3.4, end_of_page function  14.3.4,  external  file  14.1,  file
  2112. 14.1,  form  string 14.1, get procedure 14.3.5, in_file 14.1, io_exceptions
  2113. package 14.5, line  function  14.3.4,  line_length  function  14.3.4,  name
  2114. string  14.1,  new_line  procedure  14.3.4, new_page procedure 14.3.4, open
  2115. procedure 14.2.1, out_file 14.1, page function 14.3.4, page_length function
  2116. 14.3.4, put procedure  14.3.5,  read  procedure  14.2.2  14.2.3,  set_input
  2117. procedure   14.3.2,   set_line_length   14.3.3,   set_page_length   14.3.3,
  2118. set_output 14.3.2, skip_line procedure 14.3.4, skip_page procedure  14.3.4,
  2119. text_io package 14.3
  2120.  
  2121. > 14.5  Specification of the Package IO_Exceptions
  2122.  
  2123.  
  2124. This  package  defines the exceptions needed by the packages SEQUENTIAL_IO,
  2125. DIRECT_IO, and TEXT_IO.
  2126.  
  2127.  
  2128.     package IO_EXCEPTIONS is
  2129.  
  2130.        STATUS_ERROR : exception;
  2131.        MODE_ERROR   : exception;
  2132.        NAME_ERROR   : exception;
  2133.        USE_ERROR    : exception;
  2134.        DEVICE_ERROR : exception;
  2135.        END_ERROR    : exception;
  2136.        DATA_ERROR   : exception;
  2137.        LAYOUT_ERROR : exception;
  2138.  
  2139.     end IO_EXCEPTIONS;
  2140.  
  2141. > 14.6  Low Level Input-Output
  2142.  
  2143.  
  2144. A low level input-output operation is an operation  acting  on  a  physical
  2145. device.   Such  an  operation  is  handled by using one of the (overloaded)
  2146. predefined procedures SEND_CONTROL and RECEIVE_CONTROL.
  2147.  
  2148.  
  2149. A procedure SEND_CONTROL may be used  to  send  control  information  to  a
  2150. physical  device.   A  procedure RECEIVE_CONTROL may be used to monitor the
  2151. execution of an input-output operation by requesting information  from  the
  2152. physical device.
  2153.  
  2154.  
  2155. Such  procedures are declared in the standard package LOW_LEVEL_IO and have
  2156. two parameters identifying the device and the data.  However, the kinds and
  2157. formats  of  the  control  information  will   depend   on   the   physical
  2158. characteristics  of  the  machine  and the device.  Hence, the types of the
  2159. parameters are implementation-defined.   Overloaded  definitions  of  these
  2160. procedures should be provided for the supported devices.
  2161.  
  2162.  
  2163. The  visible  part  of the package defining these procedures is outlined as
  2164. follows:
  2165.  
  2166.  
  2167.     package LOW_LEVEL_IO is
  2168.        --  declarations of the possible types for DEVICE and DATA;
  2169.        --  declarations of overloaded procedures for these types:
  2170.        procedure SEND_CONTROL    (DEVICE : DEVICE_TYPE; DATA : in out DATA_TYPE);
  2171.        procedure RECEIVE_CONTROL (DEVICE : DEVICE_TYPE; DATA : in out DATA_TYPE);
  2172.     end;
  2173.  
  2174.  
  2175. The bodies of the procedures SEND_CONTROL and RECEIVE_CONTROL  for  various
  2176. devices  can  be  supplied  in the body of the package LOW_LEVEL_IO.  These
  2177. procedure bodies may be written with code statements.
  2178.  
  2179. > 14.7  Example of Input-Output
  2180.  
  2181.  
  2182. The following example shows the  use  of  some  of  the  text  input-output
  2183. facilities  in  a dialogue with a user at a terminal.  The user is prompted
  2184. to type a color, and the program responds by giving the number of items  of
  2185. that  color  available  in  stock,  according to an inventory.  The default
  2186. input and output  files  are  used.   For  simplicity,  all  the  requisite
  2187. instantiations  are  given  within one subprogram;  in practice, a package,
  2188. separate from the procedure, would be used.
  2189.  
  2190.  
  2191.     with TEXT_IO; use TEXT_IO;
  2192.     procedure DIALOGUE is
  2193.        type COLOR is (WHITE, RED, ORANGE, YELLOW, GREEN, BLUE, BROWN);
  2194.        package COLOR_IO is new ENUMERATION_IO(ENUM => COLOR);
  2195.        package NUMBER_IO is new INTEGER_IO(INTEGER);
  2196.        use COLOR_IO, NUMBER_IO;
  2197.  
  2198.        INVENTORY : array (COLOR) of INTEGER := (20, 17, 43, 10, 28, 173, 87);
  2199.        CHOICE : COLOR;
  2200.  
  2201.        procedure ENTER_COLOR (SELECTION : out COLOR) is
  2202.        begin
  2203.           loop
  2204.              begin
  2205.                 PUT("Color selected: ");  --  prompts user
  2206.                 GET(SELECTION);           --  accepts color typed, or raises exception
  2207.                 return;
  2208.              exception
  2209.                 when DATA_ERROR =>
  2210.                    PUT("Invalid color, try again.  ");  --  user has typed new line
  2211.                    NEW_LINE(2);
  2212.                    --  completes execution of the block statement
  2213.              end;
  2214.           end loop;  --  repeats the block statement until color accepted
  2215.        end;
  2216.     begin --  statements of DIALOGUE;
  2217.  
  2218.        NUMBER_IO.DEFAULT_WIDTH := 5;
  2219.  
  2220.        loop
  2221.  
  2222.           ENTER_COLOR(CHOICE);  --  user types color and new line
  2223.  
  2224.           SET_COL(5);  PUT(CHOICE); PUT(" items available:");
  2225.           SET_COL(40); PUT(INVENTORY(CHOICE));  --  default width is 5
  2226.           NEW_LINE;
  2227.        end loop;
  2228.     end DIALOGUE;
  2229.  
  2230.  
  2231. Example of an interaction (characters typed by the user are italicized):
  2232.  
  2233.     Color selected:  Black
  2234.     Invalid color, try again.
  2235.  
  2236.     Color selected:  Blue
  2237.         BLUE items available:         173
  2238.     Color selected:  Yellow
  2239.         YELLOW items available:        10
  2240.